<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
  <head>
    <meta charset="utf-8" />
    <meta name="generator" content="pandoc" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, user-scalable=yes"
    />
    <title>venv</title>
    <style type="text/css">
      code {
        white-space: pre-wrap;
      }
      span.smallcaps {
        font-variant: small-caps;
      }
      span.underline {
        text-decoration: underline;
      }
      div.column {
        display: inline-block;
        vertical-align: top;
        width: 50%;
      }
    </style>
  </head>
  <body>
    <h3 id="navigation">Navigation</h3>
    <ul>
      <li>
        <a href="https://docs.python.org/3/genindex.html" title="General Index"
          >index</a
        >
      </li>
      <li>
        <a
          href="https://docs.python.org/3/py-modindex.html"
          title="Python Module Index"
          >modules</a
        >
        |
      </li>
      <li><a href="whatnow.html" title="13. What Now?">next</a> |</li>
      <li>
        <a
          href="stdlib2.html"
          title="11. Brief Tour of the Standard Library — Part II"
          >previous</a
        >
        |
      </li>
      <li><img src="../_static/py.png" /></li>
      <li><a href="https://www.python.org/">Python</a> »</li>
      <li>
        <a href="https://docs.python.org/3/index.html">3.9.5 Documentation</a> »
      </li>
      <li><a href="index.html">The Python Tutorial</a> »</li>
      <li><div class="line-block"></div></li>
    </ul>
    <p><span id="tut-venv"></span></p>
    <h1 id="virtual-environments-and-packages">
      <span class="section-number">12. </span>Virtual Environments and
      Packages<a
        href="#virtual-environments-and-packages"
        class="headerlink"
        title="Permalink to this headline"
        >¶</a
      >
    </h1>
    <h2 id="introduction">
      <span class="section-number">12.1. </span>Introduction<a
        href="#introduction"
        class="headerlink"
        title="Permalink to this headline"
        >¶</a
      >
    </h2>
    <p>
      Python applications will often use packages and modules that don’t come as
      part of the standard library. Applications will sometimes need a specific
      version of a library, because the application may require that a
      particular bug has been fixed or the application may be written using an
      obsolete version of the library’s interface.
    </p>
    <p>
      This means it may not be possible for one Python installation to meet the
      requirements of every application. If application A needs version 1.0 of a
      particular module but application B needs version 2.0, then the
      requirements are in conflict and installing either version 1.0 or 2.0 will
      leave one application unable to run.
    </p>
    <p>
      The solution for this problem is to create a
      <a
        href="https://docs.python.org/3/glossary.html#term-virtual-environment"
        class="reference internal"
        ><span class="xref std std-term">virtual environment</span></a
      >, a self-contained directory tree that contains a Python installation for
      a particular version of Python, plus a number of additional packages.
    </p>
    <p>
      Different applications can then use different virtual environments. To
      resolve the earlier example of conflicting requirements, application A can
      have its own virtual environment with version 1.0 installed while
      application B has another virtual environment with version 2.0. If
      application B requires a library be upgraded to version 3.0, this will not
      affect application A’s environment.
    </p>
    <h2 id="creating-virtual-environments">
      <span class="section-number">12.2. </span>Creating Virtual Environments<a
        href="#creating-virtual-environments"
        class="headerlink"
        title="Permalink to this headline"
        >¶</a
      >
    </h2>
    <p>
      The module used to create and manage virtual environments is called
      <a
        href="https://docs.python.org/3/library/venv.html#module-venv"
        class="reference internal"
        title="venv: Creation of virtual environments."
        ><code class="sourceCode python">venv</code></a
      >.
      <a
        href="https://docs.python.org/3/library/venv.html#module-venv"
        class="reference internal"
        title="venv: Creation of virtual environments."
        ><code class="sourceCode python">venv</code></a
      >
      will usually install the most recent version of Python that you have
      available. If you have multiple versions of Python on your system, you can
      select a specific Python version by running <code>python3</code> or
      whichever version you want.
    </p>
    <p>
      To create a virtual environment, decide upon a directory where you want to
      place it, and run the
      <a
        href="https://docs.python.org/3/library/venv.html#module-venv"
        class="reference internal"
        title="venv: Creation of virtual environments."
        ><code class="sourceCode python">venv</code></a
      >
      module as a script with the directory path:
    </p>
    <pre><code>python3 -m venv tutorial-env</code></pre>
    <p>
      This will create the <code>tutorial-env</code> directory if it doesn’t
      exist, and also create directories inside it containing a copy of the
      Python interpreter, the standard library, and various supporting files.
    </p>
    <p>
      A common directory location for a virtual environment is
      <code>.venv</code>. This name keeps the directory typically hidden in your
      shell and thus out of the way while giving it a name that explains why the
      directory exists. It also prevents clashing with
      <code>.env</code> environment variable definition files that some tooling
      supports.
    </p>
    <p>Once you’ve created a virtual environment, you may activate it.</p>
    <p>On Windows, run:</p>
    <pre><code>tutorial-env\Scripts\activate.bat</code></pre>
    <p>On Unix or MacOS, run:</p>
    <pre><code>source tutorial-env/bin/activate</code></pre>
    <p>
      (This script is written for the bash shell. If you use the
      <strong>csh</strong> or <strong>fish</strong> shells, there are alternate
      <code>activate.csh</code> and <code>activate.fish</code> scripts you
      should use instead.)
    </p>
    <p>
      Activating the virtual environment will change your shell’s prompt to show
      what virtual environment you’re using, and modify the environment so that
      running <code>python</code> will get you that particular version and
      installation of Python. For example:
    </p>
    <pre><code>$ source ~/envs/tutorial-env/bin/activate
(tutorial-env) $ python
Python 3.5.1 (default, May  6 2016, 10:59:36)
  ...
&gt;&gt;&gt; import sys
&gt;&gt;&gt; sys.path
[&#39;&#39;, &#39;/usr/local/lib/python35.zip&#39;, ...,
&#39;~/envs/tutorial-env/lib/python3.5/site-packages&#39;]
&gt;&gt;&gt;</code></pre>
    <h2 id="managing-packages-with-pip">
      <span class="section-number">12.3. </span>Managing Packages with pip<a
        href="#managing-packages-with-pip"
        class="headerlink"
        title="Permalink to this headline"
        >¶</a
      >
    </h2>
    <p>
      You can install, upgrade, and remove packages using a program called
      <strong>pip</strong>. By default <code>pip</code> will install packages
      from the Python Package Index, &lt;<a
        href="https://pypi.org/"
        class="reference external"
        >https://pypi.org</a
      >&gt;. You can browse the Python Package Index by going to it in your web
      browser.
    </p>
    <p>
      <code>pip</code> has a number of subcommands: “install”, “uninstall”,
      “freeze”, etc. (Consult the
      <a
        href="https://docs.python.org/3/installing/index.html#installing-index"
        class="reference internal"
        ><span class="std std-ref">Installing Python Modules</span></a
      >
      guide for complete documentation for <code>pip</code>.)
    </p>
    <p>
      You can install the latest version of a package by specifying a package’s
      name:
    </p>
    <pre><code>(tutorial-env) $ python -m pip install novas
Collecting novas
  Downloading novas-3.1.1.3.tar.gz (136kB)
Installing collected packages: novas
  Running setup.py install for novas
Successfully installed novas-3.1.1.3</code></pre>
    <p>
      You can also install a specific version of a package by giving the package
      name followed by <code>==</code> and the version number:
    </p>
    <pre><code>(tutorial-env) $ python -m pip install requests==2.6.0
Collecting requests==2.6.0
  Using cached requests-2.6.0-py2.py3-none-any.whl
Installing collected packages: requests
Successfully installed requests-2.6.0</code></pre>
    <p>
      If you re-run this command, <code>pip</code> will notice that the
      requested version is already installed and do nothing. You can supply a
      different version number to get that version, or you can run
      <code>pip install --upgrade</code> to upgrade the package to the latest
      version:
    </p>
    <pre><code>(tutorial-env) $ python -m pip install --upgrade requests
Collecting requests
Installing collected packages: requests
  Found existing installation: requests 2.6.0
    Uninstalling requests-2.6.0:
      Successfully uninstalled requests-2.6.0
Successfully installed requests-2.7.0</code></pre>
    <p>
      <code>pip uninstall</code> followed by one or more package names will
      remove the packages from the virtual environment.
    </p>
    <p>
      <code>pip show</code> will display information about a particular package:
    </p>
    <pre><code>(tutorial-env) $ pip show requests
---
Metadata-Version: 2.0
Name: requests
Version: 2.7.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Author: Kenneth Reitz
Author-email: me@kennethreitz.com
License: Apache 2.0
Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
Requires:</code></pre>
    <p>
      <code>pip list</code> will display all of the packages installed in the
      virtual environment:
    </p>
    <pre><code>(tutorial-env) $ pip list
novas (3.1.1.3)
numpy (1.9.2)
pip (7.0.3)
requests (2.7.0)
setuptools (16.0)</code></pre>
    <p>
      <code>pip freeze</code> will produce a similar list of the installed
      packages, but the output uses the format that
      <code>pip install</code> expects. A common convention is to put this list
      in a <code>requirements.txt</code> file:
    </p>
    <pre><code>(tutorial-env) $ pip freeze &gt; requirements.txt
(tutorial-env) $ cat requirements.txt
novas==3.1.1.3
numpy==1.9.2
requests==2.7.0</code></pre>
    <p>
      The <code>requirements.txt</code> can then be committed to version control
      and shipped as part of an application. Users can then install all the
      necessary packages with <code>install -r</code>:
    </p>
    <pre><code>(tutorial-env) $ python -m pip install -r requirements.txt
Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
  ...
Collecting numpy==1.9.2 (from -r requirements.txt (line 2))
  ...
Collecting requests==2.7.0 (from -r requirements.txt (line 3))
  ...
Installing collected packages: novas, numpy, requests
  Running setup.py install for novas
Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0</code></pre>
    <p>
      <code>pip</code> has many more options. Consult the
      <a
        href="https://docs.python.org/3/installing/index.html#installing-index"
        class="reference internal"
        ><span class="std std-ref">Installing Python Modules</span></a
      >
      guide for complete documentation for <code>pip</code>. When you’ve written
      a package and want to make it available on the Python Package Index,
      consult the
      <a
        href="https://docs.python.org/3/distributing/index.html#distributing-index"
        class="reference internal"
        ><span class="std std-ref">Distributing Python Modules</span></a
      >
      guide.
    </p>
    <h3 id="table-of-contents">
      <a href="https://docs.python.org/3/contents.html">Table of Contents</a>
    </h3>
    <ul>
      <li>
        <a href="#" class="reference internal"
          >12. Virtual Environments and Packages</a
        >
        <ul>
          <li>
            <a href="#introduction" class="reference internal"
              >12.1. Introduction</a
            >
          </li>
          <li>
            <a href="#creating-virtual-environments" class="reference internal"
              >12.2. Creating Virtual Environments</a
            >
          </li>
          <li>
            <a href="#managing-packages-with-pip" class="reference internal"
              >12.3. Managing Packages with pip</a
            >
          </li>
        </ul>
      </li>
    </ul>
    <h4 id="previous-topic">Previous topic</h4>
    <p>
      <a href="stdlib2.html" title="previous chapter"
        ><span class="section-number">11. </span>Brief Tour of the Standard
        Library — Part II</a
      >
    </p>
    <h4 id="next-topic">Next topic</h4>
    <p>
      <a href="whatnow.html" title="next chapter"
        ><span class="section-number">13. </span>What Now?</a
      >
    </p>
    <h3 id="this-page">This Page</h3>
    <ul>
      <li><a href="https://docs.python.org/3/bugs.html">Report a Bug</a></li>
      <li>
        <a
          href="https://github.com/python/cpython/blob/3.9/Doc/tutorial/venv.rst"
          >Show Source</a
        >
      </li>
    </ul>
    <h3 id="navigation-1">Navigation</h3>
    <ul>
      <li>
        <a href="https://docs.python.org/3/genindex.html" title="General Index"
          >index</a
        >
      </li>
      <li>
        <a
          href="https://docs.python.org/3/py-modindex.html"
          title="Python Module Index"
          >modules</a
        >
        |
      </li>
      <li><a href="whatnow.html" title="13. What Now?">next</a> |</li>
      <li>
        <a
          href="stdlib2.html"
          title="11. Brief Tour of the Standard Library — Part II"
          >previous</a
        >
        |
      </li>
      <li><img src="../_static/py.png" /></li>
      <li><a href="https://www.python.org/">Python</a> »</li>
      <li>
        <a href="https://docs.python.org/3/index.html">3.9.5 Documentation</a> »
      </li>
      <li><a href="index.html">The Python Tutorial</a> »</li>
      <li><div class="line-block"></div></li>
    </ul>
    <p>
      ©
      <a href="https://docs.python.org/3/copyright.html">Copyright</a>
      2001-2021, Python Software Foundation.<br />
      The Python Software Foundation is a non-profit corporation.
      <a href="https://www.python.org/psf/donations/">Please donate.</a>
    </p>
    <p>
      Last updated on May 30, 2021.
      <a href="https://docs.python.org/3/bugs.html">Found a bug</a>?<br />
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
    </p>
  </body>
</html>
